@scrider/formatter 1.1.0 → 1.3.0

package/README.md

@@ -8,7 +8,7 @@ Schema, conversion and block handlers for rich-text content. HTML, Markdown, san
 
 ## Key Features
 
-- **Schema** — extensible format registry (31 built-in formats: inline, block, embed)
+- **Schema** — extensible format registry (32 built-in formats: inline, block, embed — including `softBreak` for Shift+Enter line breaks)
 - **HTML conversion** — `deltaToHtml()` / `htmlToDelta()` with DOM adapters (browser + Node.js)
 - **Markdown conversion** — `deltaToMarkdown()` / `markdownToDelta()` (GFM, math, footnotes)
 - **Block handlers** — tables, footnotes, alerts, columns, inline-box
@@ -65,7 +65,7 @@ const delta = htmlToDelta(html, { registry });
 ```typescript
 import { Registry, createDefaultRegistry, BlockHandlerRegistry } from '@scrider/formatter';
 
-const registry = createDefaultRegistry();  // 31 built-in formats
+const registry = createDefaultRegistry();  // 32 built-in formats
 ```
 
 ### HTML Conversion
@@ -86,6 +86,35 @@ deltaToMarkdown(delta, options?)           // Delta → Markdown string
 await markdownToDelta(markdown, options?)  // Markdown string → Delta (async)
 ```
 
+### Soft Line Break (`softBreak` embed)
+
+A `Shift+Enter` style line break that does **not** split the containing block. Stored in Delta as `{ insert: { softBreak: true } }` and round-tripped consistently across all three layers:
+
+| Direction | Encoding |
+|-----------|----------|
+| HTML      | `<br data-scrider-embed>` (the marker disambiguates it from the `<br>` placeholder inside an empty paragraph) |
+| Markdown  | `"  \n"` by default — GFM hard break; switch to inline `<br>` via `deltaToMarkdown(delta, { softBreakStyle: 'html' })` |
+
+`htmlToDelta` also recognises bare `<br>` between content (e.g. `<p>foo<br>bar</p>`) as a soft break, while keeping the leading / placeholder shapes (`<p><br></p>`, `<p><br>foo</p>`) as regular newlines for backward compatibility.
+
+```typescript
+import { Delta, deltaToHtml, deltaToMarkdown } from '@scrider/formatter';
+
+const doc = new Delta()
+  .insert('hello')
+  .insert({ softBreak: true })
+  .insert('world\n');
+
+deltaToHtml(doc);
+// → '<p>hello<br data-scrider-embed>world</p>'
+
+deltaToMarkdown(doc);
+// → 'hello  \nworld'
+
+deltaToMarkdown(doc, { softBreakStyle: 'html' });
+// → 'hello<br>world'
+```
+
 ### Sanitization
 
 ```typescript

package/dist/index.cjs

@@ -63,6 +63,7 @@ __export(index_exports, {
   dividerFormat: () => dividerFormat,
   escapeHtml: () => escapeHtml,
   extractBoxOpAttributes: () => extractBoxOpAttributes,
+  extractTableRegion: () => extractTableRegion,
   fontFormat: () => fontFormat,
   footnoteRefFormat: () => footnoteRefFormat,
   footnotesBlockHandler: () => footnotesBlockHandler,
@@ -77,6 +78,7 @@ __export(index_exports, {
   isAdapterAvailable: () => isAdapterAvailable,
   isElement: () => isElement,
   isRemarkAvailable: () => isRemarkAvailable,
+  isTableNewlineOp: () => isTableNewlineOp,
   isTextNode: () => isTextNode,
   isValidColor: () => isValidColor,
   isValidHexColor: () => isValidHexColor,
@@ -89,10 +91,12 @@ __export(index_exports, {
   markdownToDeltaSync: () => markdownToDeltaSync,
   nodeAdapter: () => nodeAdapter,
   normalizeDelta: () => normalizeDelta,
+  preloadRemark: () => preloadRemark,
   sanitizeDelta: () => sanitizeDelta,
   sizeFormat: () => sizeFormat,
   slugify: () => slugify,
   slugifyWithDedup: () => slugifyWithDedup,
+  softBreakFormat: () => softBreakFormat,
   strikeFormat: () => strikeFormat,
   subscriptFormat: () => subscriptFormat,
   superscriptFormat: () => superscriptFormat,
@@ -2017,7 +2021,13 @@ var EMBED_RENDERERS = {
     const id = typeof value === "string" ? value : String(value);
     return `<sup class="footnote-ref"><a href="#fn-${escapeHtml(id)}" id="fnref-${escapeHtml(id)}">[${escapeHtml(id)}]</a></sup>`;
   },
-  divider: () => "<hr>"
+  divider: () => "<hr>",
+  // Soft line break (Shift+Enter equivalent). Emitted with an explicit
+  // `data-scrider-embed` marker so that html-to-delta can distinguish this
+  // embed from the placeholder `<br>` that appears inside an empty
+  // paragraph (`<p><br></p>`) without relying solely on positional
+  // heuristics. See `soft-break.ts` for the format definition.
+  softBreak: () => "<br data-scrider-embed>"
 };
 var TAG_TO_INLINE_FORMAT = {
   strong: { format: "bold", value: true },
@@ -2255,6 +2265,33 @@ var imageFormat = {
   }
 };
 
+// src/schema/formats/embed/soft-break.ts
+var softBreakFormat = {
+  name: "softBreak",
+  scope: "embed",
+  normalize(value) {
+    return !!value;
+  },
+  validate(value) {
+    return value === true;
+  },
+  render() {
+    return "<br data-scrider-embed>";
+  },
+  match(element) {
+    if (element.tagName.toLowerCase() !== "br") return null;
+    if (!element.hasAttribute("data-scrider-embed")) return null;
+    return { value: true };
+  }
+  // NB: Markdown rendering is intentionally NOT implemented on the format
+  // itself. The choice between `"  \n"` (GFM spaces) and inline `<br>`
+  // depends on the caller-provided `softBreakStyle` option on
+  // `deltaToMarkdown`, so the converter handles it as a built-in special
+  // case instead of going through `Format.toMarkdown`. The Markdown side
+  // of the round-trip is symmetric: `markdownToDelta` recognises both
+  // `break` AST nodes and inline `<br>` HTML and emits this embed.
+};
+
 // src/schema/formats/embed/video.ts
 var videoFormat = {
   name: "video",
@@ -2357,6 +2394,7 @@ var defaultEmbedFormats = [
   videoFormat,
   formulaFormat,
   dividerFormat,
+  softBreakFormat,
   blockFormat,
   footnoteRefFormat
 ];
@@ -3187,7 +3225,12 @@ function htmlToDelta(html, options = {}) {
       return;
     }
     if (tagName === "br") {
-      context.pushNewline();
+      const hasMarker = node.hasAttribute("data-scrider-embed");
+      if (hasMarker || hasMeaningfulPrevSibling(node)) {
+        context.pushEmbed({ softBreak: true });
+      } else {
+        context.pushNewline();
+      }
       return;
     }
     processChildren(node);
@@ -3621,6 +3664,23 @@ function normalizeText(text, pendingText, atLineStart) {
   }
   return text;
 }
+function hasMeaningfulPrevSibling(brNode) {
+  const parent = brNode.parentNode;
+  if (!parent) return false;
+  const children = parent.childNodes;
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i];
+    if (!child) continue;
+    if (child === brNode) return false;
+    if (child.nodeType === NODE_TYPE.TEXT_NODE) {
+      const text = child.textContent ?? "";
+      if (text.trim().length > 0) return true;
+    } else if (isElement(child)) {
+      return true;
+    }
+  }
+  return false;
+}
 function findTagHandler(handlers, element, tagName) {
   const className = element.getAttribute("class");
   if (className) {
@@ -3756,7 +3816,9 @@ function deltaToMarkdown(delta, options = {}) {
     embedRenderers = {},
     blockHandlers,
     prettyHtml = false,
-    registry
+    registry,
+    softBreakStyle = "spaces",
+    trimTrailingNewlines = false
   } = options;
   const useLatexDelimiters = mathSyntax === "latex";
   const lines = splitIntoLines2(delta.ops);
@@ -3772,7 +3834,9 @@ function deltaToMarkdown(delta, options = {}) {
     const isBlockquote = !!attrs.blockquote;
     if (typeof attrs["table-row"] === "number" && typeof attrs["table-col"] === "number") {
       const tableLines = collectTableLines2(lines, i);
-      result.push(renderMarkdownTable(tableLines, embedRenderers, useLatexDelimiters, registry));
+      result.push(
+        renderMarkdownTable(tableLines, embedRenderers, useLatexDelimiters, registry, softBreakStyle)
+      );
       result.push("");
       i += tableLines.length - 1;
       lastListType = null;
@@ -3788,7 +3852,16 @@ function deltaToMarkdown(delta, options = {}) {
       const codeLines = collectCodeBlock(lines, i);
       const language = getCodeBlockLanguage2(attrs);
       const code = codeLines.map(
-        (l) => renderLineContent2(l.ops, embedRenderers, true, false, blockHandlers, false, registry)
+        (l) => renderLineContent2(
+          l.ops,
+          embedRenderers,
+          true,
+          false,
+          blockHandlers,
+          false,
+          registry,
+          softBreakStyle
+        )
       ).join("\n");
       if (language === "math") {
         if (mathBlock === false) {
@@ -3838,7 +3911,8 @@ ${code}
       useLatexDelimiters,
       blockHandlers,
       prettyHtml,
-      registry
+      registry,
+      softBreakStyle
     );
     if (!content && !hasBlockFormat(attrs)) {
       result.push(preserveEmptyLines ? "<br>" : "");
@@ -3854,7 +3928,8 @@ ${code}
     lastIndent = indent;
     lastWasBlockquote = isBlockquote;
   }
-  return result.join("\n");
+  const md = result.join("\n");
+  return trimTrailingNewlines ? md.replace(/\n+$/, "") : md;
 }
 function hasBlockFormat(attrs) {
   return !!(attrs.header || attrs.list || attrs.blockquote || attrs["code-block"] || attrs.align || attrs.indent);
@@ -3939,7 +4014,7 @@ function collectTableLines2(lines, startIndex) {
   }
   return result;
 }
-function renderMarkdownTable(tableLines, embedRenderers, useLatexDelimiters = false, registry) {
+function renderMarkdownTable(tableLines, embedRenderers, useLatexDelimiters = false, registry, softBreakStyle = "spaces") {
   const rows = /* @__PURE__ */ new Map();
   for (const line of tableLines) {
     const attrs = line.attributes;
@@ -3976,7 +4051,9 @@ function renderMarkdownTable(tableLines, embedRenderers, useLatexDelimiters = fa
   const mdLines = [];
   if (headerRows.length > 0) {
     for (const [, row] of headerRows) {
-      mdLines.push(renderMdRow(row.cells, maxCol, embedRenderers, useLatexDelimiters, registry));
+      mdLines.push(
+        renderMdRow(row.cells, maxCol, embedRenderers, useLatexDelimiters, registry, softBreakStyle)
+      );
     }
     mdLines.push(renderMdSeparator(maxCol, colAligns));
   } else {
@@ -3984,15 +4061,19 @@ function renderMarkdownTable(tableLines, embedRenderers, useLatexDelimiters = fa
     for (let col = 0; col <= maxCol; col++) {
       emptyRow.set(col, { ops: [] });
     }
-    mdLines.push(renderMdRow(emptyRow, maxCol, embedRenderers, useLatexDelimiters, registry));
+    mdLines.push(
+      renderMdRow(emptyRow, maxCol, embedRenderers, useLatexDelimiters, registry, softBreakStyle)
+    );
     mdLines.push(renderMdSeparator(maxCol, colAligns));
   }
   for (const [, row] of bodyRows) {
-    mdLines.push(renderMdRow(row.cells, maxCol, embedRenderers, useLatexDelimiters, registry));
+    mdLines.push(
+      renderMdRow(row.cells, maxCol, embedRenderers, useLatexDelimiters, registry, softBreakStyle)
+    );
   }
   return mdLines.join("\n");
 }
-function renderMdRow(cells, maxCol, embedRenderers, useLatexDelimiters = false, registry) {
+function renderMdRow(cells, maxCol, embedRenderers, useLatexDelimiters = false, registry, softBreakStyle = "spaces") {
   const parts = [];
   for (let col = 0; col <= maxCol; col++) {
     const cell = cells.get(col);
@@ -4003,7 +4084,10 @@ function renderMdRow(cells, maxCol, embedRenderers, useLatexDelimiters = false,
       useLatexDelimiters,
       void 0,
       false,
-      registry
+      registry,
+      softBreakStyle,
+      true
+      // inTableCell — softBreak must use <br>, never "  \n"
     ) : "";
     parts.push(content.replace(/\|/g, "\\|"));
   }
@@ -4032,7 +4116,7 @@ function getCodeBlockLanguage2(attributes) {
   }
   return void 0;
 }
-function renderLineContent2(ops, embedRenderers, inCodeBlock, useLatexDelimiters = false, blockHandlers, prettyHtml = false, registry) {
+function renderLineContent2(ops, embedRenderers, inCodeBlock, useLatexDelimiters = false, blockHandlers, prettyHtml = false, registry, softBreakStyle = "spaces", inTableCell = false) {
   let result = "";
   for (const op of ops) {
     const attrs = op.attributes;
@@ -4052,7 +4136,9 @@ function renderLineContent2(ops, embedRenderers, inCodeBlock, useLatexDelimiters
         useLatexDelimiters,
         blockHandlers,
         prettyHtml,
-        registry
+        registry,
+        softBreakStyle,
+        inTableCell
       );
     }
   }
@@ -4086,13 +4172,17 @@ function renderInlineText2(text, attributes) {
   }
   return result;
 }
-function renderEmbed2(embed, attributes, customRenderers, useLatexDelimiters = false, blockHandlers, prettyHtml = false, registry) {
+function renderEmbed2(embed, attributes, customRenderers, useLatexDelimiters = false, blockHandlers, prettyHtml = false, registry, softBreakStyle = "spaces", inTableCell = false) {
   const entries = Object.entries(embed);
   if (entries.length === 0) return "";
   const firstEntry = entries[0];
   if (!firstEntry) return "";
   const embedType = firstEntry[0];
   const embedValue = firstEntry[1];
+  if (embedType === "softBreak") {
+    if (inTableCell) return "<br>";
+    return softBreakStyle === "html" ? "<br>" : "  \n";
+  }
   if (embedType === "block" && blockHandlers) {
     const blockData = embedValue;
     if (blockData && typeof blockData.type === "string") {
@@ -4243,6 +4333,8 @@ var remarkGfm = null;
 var remarkMath = null;
 var unified = null;
 function isRemarkAvailable() {
+  if (unified && remarkParse) return true;
+  if (typeof require === "undefined") return false;
   try {
     require.resolve("unified");
     require.resolve("remark-parse");
@@ -4251,8 +4343,8 @@ function isRemarkAvailable() {
     return false;
   }
 }
-async function loadRemark() {
-  if (unified) return;
+async function preloadRemark() {
+  if (unified && remarkParse && remarkGfm) return true;
   try {
     const [unifiedMod, remarkParseMod, remarkGfmMod] = await Promise.all([
       import("unified"),
@@ -4263,15 +4355,16 @@ async function loadRemark() {
     remarkParse = remarkParseMod.default;
     remarkGfm = remarkGfmMod.default;
   } catch {
-    throw new Error(
-      "remark is not installed. Install with: pnpm add unified remark-parse remark-gfm"
-    );
+    return false;
   }
-  try {
-    const remarkMathMod = await import("remark-math");
-    remarkMath = remarkMathMod.default;
-  } catch {
+  if (!remarkMath) {
+    try {
+      const remarkMathMod = await import("remark-math");
+      remarkMath = remarkMathMod.default;
+    } catch {
+    }
   }
+  return true;
 }
 function preprocessMarkdown(markdown, mathBlock) {
   markdown = markdown.replace(/\\\((.+?)\\\)/g, (_match, content) => `$${content}$`);
@@ -4295,9 +4388,11 @@ async function markdownToDelta(markdown, options = {}) {
     nodeHandlers = {}
   } = options;
   markdown = preprocessMarkdown(markdown, mathBlock);
-  await loadRemark();
-  if (!unified || !remarkParse) {
-    throw new Error("Failed to load remark");
+  const loaded = await preloadRemark();
+  if (!loaded || !unified || !remarkParse) {
+    throw new Error(
+      "remark is not installed. Install with: pnpm add unified remark-parse remark-gfm"
+    );
   }
   let processor = unified().use(remarkParse);
   if (gfm && remarkGfm) {
@@ -4326,6 +4421,11 @@ function markdownToDeltaSync(markdown, options = {}) {
   } = options;
   markdown = preprocessMarkdown(markdown, mathBlock);
   if (!unified || !remarkParse) {
+    if (typeof require === "undefined") {
+      throw new Error(
+        "markdownToDeltaSync requires remark to be preloaded in this environment. `require()` is not available (likely browser ESM). Call `await preloadRemark()` once on application startup before using the sync API, or use the async `markdownToDelta()` instead."
+      );
+    }
     try {
       const unifiedMod = require("unified");
       const remarkParseMod = require("remark-parse");
@@ -4571,7 +4671,7 @@ function astToDelta(tree, customHandlers, mathBlock, mermaidBlock, plantumlBlock
         footnoteDefinitions.set(node.identifier ?? "", node);
         break;
       case "break":
-        context.pushNewline();
+        context.pushEmbed({ softBreak: true });
         break;
       case "html": {
         const htmlContent = node.value ?? "";
@@ -4877,8 +4977,8 @@ function astToDelta(tree, customHandlers, mathBlock, mermaidBlock, plantumlBlock
       context.pushNewline();
       return;
     }
-    if (/^<br\s*\/?>$/i.test(html)) {
-      context.pushNewline();
+    if (/^<br\b[^>]*\/?>$/i.test(html)) {
+      context.pushEmbed({ softBreak: true });
       return;
     }
   }
@@ -4914,6 +5014,54 @@ function astToDelta(tree, customHandlers, mathBlock, mermaidBlock, plantumlBlock
   }
   return delta;
 }
+
+// src/conversion/markdown/table-region.ts
+var import_delta11 = require("@scrider/delta");
+function isTableNewlineOp(op) {
+  if (!op || !(0, import_delta11.isInsert)(op) || !(0, import_delta11.isTextInsert)(op)) return false;
+  if (!op.insert.includes("\n")) return false;
+  return !!op.attributes && "table-row" in op.attributes;
+}
+function extractTableRegion(ops, hintOpIdx) {
+  if (hintOpIdx < 0 || hintOpIdx >= ops.length) return null;
+  let probeIdx = -1;
+  for (let i = hintOpIdx; i < ops.length; i++) {
+    const op = ops[i];
+    if (!op || !(0, import_delta11.isInsert)(op)) continue;
+    if ((0, import_delta11.isTextInsert)(op) && op.insert.includes("\n")) {
+      probeIdx = i;
+      break;
+    }
+  }
+  if (probeIdx < 0) return null;
+  if (!isTableNewlineOp(ops[probeIdx])) return null;
+  let endOpIdx = probeIdx;
+  for (let i = probeIdx + 1; i < ops.length; i++) {
+    const op = ops[i];
+    if (!op || !(0, import_delta11.isInsert)(op)) break;
+    if ((0, import_delta11.isTextInsert)(op) && op.insert.includes("\n")) {
+      if (isTableNewlineOp(op)) {
+        endOpIdx = i;
+      } else {
+        break;
+      }
+    }
+  }
+  let startOpIdx = 0;
+  for (let i = probeIdx - 1; i >= 0; i--) {
+    const op = ops[i];
+    if (!op || !(0, import_delta11.isInsert)(op)) {
+      startOpIdx = i + 1;
+      break;
+    }
+    if ((0, import_delta11.isTextInsert)(op) && op.insert.includes("\n") && !isTableNewlineOp(op)) {
+      startOpIdx = i + 1;
+      break;
+    }
+  }
+  const regionOps = ops.slice(startOpIdx, endOpIdx + 1);
+  return { startOpIdx, endOpIdx, ops: regionOps };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALERT_TYPES,
@@ -4948,6 +5096,7 @@ function astToDelta(tree, customHandlers, mathBlock, mermaidBlock, plantumlBlock
   dividerFormat,
   escapeHtml,
   extractBoxOpAttributes,
+  extractTableRegion,
   fontFormat,
   footnoteRefFormat,
   footnotesBlockHandler,
@@ -4962,6 +5111,7 @@ function astToDelta(tree, customHandlers, mathBlock, mermaidBlock, plantumlBlock
   isAdapterAvailable,
   isElement,
   isRemarkAvailable,
+  isTableNewlineOp,
   isTextNode,
   isValidColor,
   isValidHexColor,
@@ -4974,10 +5124,12 @@ function astToDelta(tree, customHandlers, mathBlock, mermaidBlock, plantumlBlock
   markdownToDeltaSync,
   nodeAdapter,
   normalizeDelta,
+  preloadRemark,
   sanitizeDelta,
   sizeFormat,
   slugify,
   slugifyWithDedup,
+  softBreakFormat,
   strikeFormat,
   subscriptFormat,
   superscriptFormat,